package loveqq.niceexcel.read.handler;

import loveqq.niceexcel.core.metadata.CellHeadMeta;
import loveqq.niceexcel.read.ReadContext;
import org.apache.poi.ss.usermodel.Cell;

/**
 * 表头定位数据拦截处理器
 * <pre>{@code
 *
 *  CellReadHandler cellHandler;
 *  LocateDataReadHandler handler;
 *
 *  for (Cell cell : row) {
 *      cellHandler.onCellRead();
 *      // 全部定位数据开始前
 *      if (!handler.beforeLocateData()) {
 *          continue;
 *      }
 *      for (CellHeadMeta locateDataHeadMeta : locateDataHeadMetas) {
 *          // 定位数据成功, 开始处理
 *          if (!handler.onLocatedDataBegin()) {
 *              continue;
 *          }
 *          ......  // 处理单元格数据
 *          // 数据处理结束
 *          handler.onLocatedDataBegin();
 *      }
 *      // 全部定位数据结束
 *      handler.afterLocateData();
 *  }
 *
 * }</pre>
 *
 * @author zhongjh@tsintergy.com
 * @date 2022-08-20
 */
public interface LocateDataReadHandler extends ReadHandler {

    /**
     * 单个cell所有匹配的定位数据开始前
     *
     * @param context 读取上下文
     * @param cell    单元格
     * @return 是否继续定位数据
     */
    default boolean beforeLocateData(ReadContext context, Cell cell) {
        return true;
    }

    /**
     * 单个cell所有匹配定位数据处理结束后
     *
     * @param context 读取上下文
     * @param cell    单元格
     */
    default void afterLocateData(ReadContext context, Cell cell) {
    }

    /**
     * cell匹配到单个表头定位(CellHeadMeta)开始处理时
     *
     * @param context            读取上下文
     * @param cell               单元格
     * @param locateDataHeadMeta 表头定位数据元信息
     * @return 定位成功是否继续处理数据
     */
    default boolean onLocatedDataBegin(ReadContext context, Cell cell, CellHeadMeta locateDataHeadMeta) {
        return true;
    }

    /**
     * cell匹配到单个表头定位(CellHeadMeta)处理数据结束时
     *
     * @param context            读取上下文
     * @param cell               单元格
     * @param locateDataHeadMeta 表头定位数据元信息
     */
    default void onLocatedDataEnd(ReadContext context, Cell cell, CellHeadMeta locateDataHeadMeta) {
    }

}
